The HelpCt driver supports controls that display and edit styled "help" text. FaceWare makes extensive use of this control type to provide on-line help. Note that HelpCt controls are not well-suited to display user-editable text. To do the latter, use BaseCt's editable text controls, or the TextCt or StylCt controls included with the EditControls product.
Basic Operation
The current text displayed in a HelpCt control is obtained from the TEXT/styl resource pair that has a resource ID number equal to the control's value. Both SetVal and SetCtlValue can be used to reset this value and thereby "flip" between blocks of text.
In many cases you will not need to display more than one text block in a HelpCt control, and you can simply set the control's min = max = value to the resource ID of a single TEXT/styl pair.
For proper operation, the control should be of type Editable, Return keys should be accepted, and Idle messages should be sent to the control. The control's value is used for data linking. No use is made of the resource type and ID fields. HelpCt controls look best with solid bodies, one-pixel frames, and no indent.
The TEHandle associated with a HelpCt control can be found in cHiData after calling GetCtl to get control information.
Auto-Scrolling
The default behavior of the Enter key is to hit the default control (= the close box in this window). If you would prefer to have the Enter key auto-scroll to the current selection, then check the "Enter" item in the "Keys Accepted" menu so that the Enter key gets passed to the HelpCt control.
Read Only Text
The lock icon seen at the top, right of this window can be used to toggle between locked (= read only) and unlocked (= editable) states. If you prefer to display text that can never be edited by the user, then add 2 to the control's VarCode. In this case the lock icon will not appear, and the help text will be "Read Only".
Multiple Topics
HelpCt supports standard items 1901-1990 which can be used to switch topics in response to menu selections. When receiving a message from such a standard item, HelpCt calculates a resource ID using the following formula,
res ID = standard label number - 1901 + control min
and loads the corresponding TEXT/styl resources.
For example, to support the selection of topics corresponding to TEXT/styl resources 1051 to 1060, you would set the HelpCt control's min and max values to 1051 and 1060, respectively, and then create a menu with items labeled from 1901 to 1910 (e.g. "MyItem#1901"). Each selection from this menu would then cause HelpCt to load the corresponding TEXT/styl resources.
SubTopics Menu
Each HelpCt control has a default style that can be set using ViewIt's Style menu when in editing mode. If this default style is not plain, then HelpCt uses it to build a subtopics menu by searching the help text for all strings that match the control's default style.
The subtopics menu created by HelpCt has a menuID equal to 255 and can be attached to any hierarchical menu item (see the "Subtopic" item above), and is also automatically attached to the standard item (if any) associated with the control's current value. A control with Min = 1051, Max = 1060, and Value = 1053, for example, would have its suptopics menu attached to the standard item with label #1903.
Hierarchical Topics (Advanced Option)
In the case where the help topics for a single control can be arranged into groups of subtopics, you can get HelpCt to automatically build the corresponding hierarchical help menus by setting the control's VarCode equal to one.
To build these help menus, HelpCt searches for all TEXT/styl resource pairs with resource IDs between the control's min and max values. One help menu is allocated for each contiguous block of resource IDs (i.e. skip one or more resource ID numbers to force a new menu to be created). The help items in each menu consist of the resource names of the associated TEXT/styl resources.
The hierarchical help menus will have menuIDs from 236-253, and each help item is a standard HelpCt menu item labeled from 1901-1990 (as described above). A new set of menus is allocated for each HelpCt control, and these menus are only inserted when the control is selected, so conflicts between HelpCt controls will never occur.
The only additional work needed to make use of these hierarchical menus is to provide access to them. This is easily done by creating another menu which has hierarchical menu items linked to the hierarchical help menus (236-253).
Creating New Help
If you create a new HelpCt control and associate it with a non-existing TEXT/styl resource pair, then HelpCt will display a message that the resources are missing and allow you to enter new text. You can then save this text to the current resource file using the standard "Save" menu item (vs. the "Save All to disk" item which saves the FWND template).
An alternative way to create new help text is to use ResEdit to create TEXT/styl resources which can later be associated with HelpCt controls and further edited.
Warning: The current version of HelpCt does not track whether the text in the control is "dirty" due to editing, so save your changes before switching topics or closing the window!
Standard Menu Items
The standard items which appear in this window's menus are supported by HelpCt (Save, Revert, ..., Next Case). HelpCt also supports the standard "Go To" item which it renames "Next Topic" to switch main topics (see the ViewIt Help for an example). ViewIt's Font, Size, Style, and Color menus are also supported.
When printing via the "Print..." standard item, HelpCt resets the parent window's title to the name of the TEXT resource being printed, and prints the name of this resource and a page # at the top of each page. "Print All..." prints all of the TEXT/styl resources associated with the control (resID = min to max).
Limitations
All limitations of Apple's TextEdit (such as 32K per text block) apply. No support for hand scrolling. No more than 18 hierarchical help menus and 90 help items are created per HelpCt control. The global hilite color is always used whether that option is checked or not.
The line height is constant within each text block and is determined by the height of the control's current font and font size. Thus, for example, to change the line height of the text you are now reading, enter edit mode and reset this control's font size.
